

                            C O N V E R T      

                         version 2.0, March 3th, 1992

                                 User Manual

        ***************************************************************

                                  Contents

                   1. Introduction - What does "Convert" ?
                   2. Getting started
                   3. Working with "Convert"
                   4. Creating own conversion descriptions
                   5. Error messages
                   6. The shell version "Cvt"


        ***************************************************************


        1. Introduction


        "Convert" is a powerful file conversion program. It covers the
        application domain of all ASCII conversion tools between Amiga
        and MS-DOS or any other computer system. This means, that file
        conversion with "Convert" does NOT affect the physical format of
        a file but only its contents. Physical conversion is not subject
        of "Convert" and thus assigned to tools like "CrossDOS".

        "Convert" can be used to replace bytes or pairs of bytes in a
        file by another byte or another pair of bytes or by nothing.
        Therefore it can be used for tasks as follows:

        - replacing TABs in an ASCII file with blank character(s)
        - stripping controls in an ASCII file
        - converting ASCII-files between Amiga and MS-DOS, MS-DOS and
          Amiga, Amiga and Mac, Mac and Sun, Amiga and Sun etc.

        What are "conversion descriptions" ?

        All that "Convert" needs, is a set of "replacement records"
        which it can apply to its input files. This set is in the
        following called "conversion description".
        You can create your individual conversion descriptions by
        creating several "replacement records" with a text editor using
        the simple syntax described in chapter 4. These "records" are
        stored to a conversion description file which can be parsed by
        "Convert".

        The draft of specifying the conversion by a simple text file
        makes "Convert" more powerful than any other conversion tool
        and thus allows the application of "Convert" for almost all
        conversion problems.


        ***************************************************************


        2. Getting started


        Installation

        To install "Convert" double-click the "Install" icon. This short
        shell script will do the following things:

        - Copying "reqtools.library" to the LIBS: directory.
        - Copying "Cvt" to the C: directory.

        Furthermore, you must have a directory from where "Convert" reads
        its conversion description files. If this directory is not the
        same as the one where "Convert" is placed, you must assign the
        logical device "CVT:" to it.
        If "Convert" starts, first it looks in the current directory for
        conversion descriptions. If it cannot find any matching file
        (with the extension ".cvt"), it tries to get files from "CVT:".
        NOTE: If "Convert" cannot find any description file, it will
        NOT work !


        Starting "Convert"

        You can start "Convert" by entering its name in the shell or by
        double-clicking its icon.
        If the program can locate at least one conversion description,
        it opens a window which contains the control panel of "Convert".
        This panel consists of following elements:

        * Source file list *

        This list on the left side of the buttons displays the names of
        all files to be converted. The names are shown without path
        name, except if you select two files in different directories
        with the same name. Then the whole path name is displayed.

        * Conversion list *

        This list on the right side of the buttons displays the names
        of the conversion description files which "Convert" could locate
        at the start. The currently selected conversion description file
        is shown by a high-lighted selection. By default the first name
        of the list is selected.

        * Button "Clear" *

        You can use this button for deleting the current contents of the
        source file list. If the files in this list have not been
        converted yet, you will be asked to confirm your decision.

        * Button "Add files..." *

        If you click this button, a file requester will appear. You can
        then select the files which you want to convert by clicking on
        the file names while holding the SHIFT key. In addition there are
        buttons for selecting and de-selecting all files and for pattern
        matching (great, Nico ! :-) ).
        Press the button "Ok" to add the selected files to the source file
        list.

        * Button "Remove" *

        You can use this button for deleting the currently selected item
        in the source file list. If the files in this list have not been
        converted yet, you will be asked to confirm your decision.

        * Button "Start" *

        A click on this button starts the conversion process.

        * Button "About..." *

        Click this button to get short information about "Convert".

        * Button "Quit" *

        You can use this button for exiting "Convert". If the files in the
        source file list have not been converted yet, you will be asked
        to confirm your decision. You can also quit by clicking in the
        close gadget of "Convert"'s window.

        * Cycle-gadget "Replace Original/Target Directory"

        This cycle-gadget can be used to toggle between the following two
        modes:

        1. replacement mode
        2. duplication mode

        The replacement mode is active, when the gadget shows the text
        "Replace Original". Former versions of "Convert" (up to v1.12)
        only provide this mode. In this mode "Convert" replaces the
        original file with the converted version.
        If you choose the duplication mode, a directory requester will
        appear and you have to select a target directory, where "Convert"
        will write the converted files. The name of the target directory
        is then displayed within the cycle-gadget.


        ***************************************************************


        3. Working with "Convert"


        When you have started "Convert" from the shell or from workbench,
        it will open a window which contains a small control panel.
        The source file list on the left side of the buttons is empty,
        so the buttons "Clear" and "Start" are "ghosted".
        Whenever you want to append files to the source file list, press
        the button "Add files". A file requester will appear which allows
        you to select the desired files. Press the "Ok" button to
        append the files to the source file list.
        If you do not want to overwrite the old files with the converted
        versions, then you can specify a target directory for the
        converted files by pressing the cycle-gadget at the botton of the
        window. When you have chosen a target directory, its name will
        be displayed within the gadget.
        Before you start the conversion process, make sure you have
        selected the correct conversion description in the list on the
        right side of the buttons. The current description is shown
        beneath the list.
        The conversion process can be started by pressing the "Start"
        button. "Convert" will open a window which gives you a simple
        trace about the conversion.
        If the conversion description contains no syntax errors, the
        conversion should be performed without any problem. Otherwise
        you have to correct the description file with a text editor.
        At the end "Convert" informs you with a simple requester about
        the success of the conversion process.
        If there were no problems, you can return to the control panel.
        Usually you will want to clear the source file list for the next
        conversion procedure or to quit from "Convert".


        ***************************************************************


        4. Creating own conversion descriptions


        A conversion description file consists of a set of replacement
        records. Such a record describes how a byte or a pair of bytes
        should be replaced by another byte or another pair of bytes or
        by nothing.
        The structure of a conversion description can thus be described
        with the following grammar in EBNF:

        ConvDescr = { ReplRec }.

        ReplRec   = Primary '->' [ Primary ].

        Primary   = Byte [ ',' Byte ]
                  | String.

        Byte      = digit { digit }
                  | '"' char '"'.

        String    = '"' char char '"'.

        Character sets:
          digit = any decimal digit (0-9).
          char  = any character but '"'.

        NB.: "Byte" always stands for 1 byte, "String" always stands for
             2 bytes !

        Each replacement record must be written in a separate line.

        Furthermore a conversion description may contain comments which
        are written like in the programming languages Ada or Eiffel
        (beginning with "--", until end of line). The comments must NOT
        occur after a replacement record.

        Example:

        -- this is a short example of a conversion description

        --replace byte pair (14,37) with byte 121
        14,37->121
        --replace byte 154 with byte 254
        154->254
        --strip byte pair (31,201)
        31,201->
        --replace byte "A" (character) with 13
        "A"->13
        --replace string "RK" with string "SN" (for byte-fanatics)
        "R","K"->"S","N"
        --replace string "<<" with string ">>" (for lazy writers)
        "<<"->">>"

        --the following lines are incorrect:
        14,37,->12
        ->13
        20->41 --this comment does not belong to here !
        --string "XX" stands for byte pair, byte "Y" is too much
        "XX","Y"->
        --if you want to convert '"' then use numbers !
        """->22

        (end of file)


        ***************************************************************


        5. Error Messages


        "Convert" distinguishes between internal and user errors.

        Internal errors are reported by a short output in the shell
        window or a requester with the title "FATAL ERROR". If an
        internal error occurs, the reason may be a lack of memory. The
        execution of "Convert" is immediately terminated and you have
        to increase the free memory size by quitting from another
        application before restarting "Convert".
        There exists one special internal error which is raised, if
        "Convert" cannot find any conversion description files. This
        error is named

        "Cannot find a conversion description ! - No conversion possible."


        User errors are reported in a requester named "Information".
        Errors of this kind may occur during a conversion process.
        In this case "Convert" will stop the process and return to the
        control panel. The user errors are listed below.

        "Error in conversion description file in line x"
        "Conversion description file not found"

        These errors may occur at the beginning of the conversion process
        when "Convert" tries to open and to parse the current
        conversion description file.
        The first error is reported, whenever a syntax error has been
        encountered in the description file. See chapter 4 for further
        details.
        The second error is reported, when "Convert" cannot open the
        description file. Since the list of description files is built
        at the start of "Convert", another task may have removed the
        requested file.

        "File not found or conversion of empty file attempted"

        This error may occur during the conversion process, when
        "Convert" cannot open a source file. Another task may have
        removed the file between the selection of the file and the
        beginning of the conversion process.

        "Could not get/set file date"

        This message appears if the handler process of the device from
        which the source files are read does not understand the SET_DATE
        command. "Convert" tries to save the old date of a file, since
        only the file structure should be changed.
        If the device driver of your harddisk does not support date
        setting, then try the conversion using another device, i.e. RAM:.

        "Cannot create temporary file"

        In general "Convert" does not save the converted file directly
        over the original file, but creates a temporary file in the same
        directory where the original file is located. If a write-protected
        file with the same name ("CvtTmp_<task address>") exists in this
        directory ,this message tells you that "Convert" will save the
        converted file directly over the original file.

        "Cannot write converted file"

        If one of the source files is opened for output by another
        task during the conversion process, this error will be reported.

        "Cannot lock target directory"

        This message may only appear in duplication mode. It indicates
        that "Convert" could not get read access to the specified target
        directory. A possible reason is that there is another task that
        has exclusive (write) access to the directory.

        "Internal overflow: too many subdirectories"

        This message may only appear in duplication mode. It indicates 
        then the path name of a source file to be converted contains more
        than 20 subdirectory names.


        ***************************************************************


        6. The shell version "Cvt"


        This program is a reduced version of "Convert". It does not
        provide a graphical user interface but accepts all parameters
        from the shell.

        If you call "Cvt" without any parameters it will print the
        following short description:

         Convert  conversion utility v2.0 for AmigaDOS
        Copyright (C) 1992-1993 by Rainer Koppler

        USAGE: Cvt "FILES" <file> { <file> }
                   ("DESCRIPTION"|"DSC") <ConversionDescription>
                   [("TARGET"|"TRG") <TargetDirectory>]
                   ["QUIET"]

        If you call "Cvt" with the parameter "?", it will prompt you with
        the following AmigaDOS command template:

        FILES/...,DESCRIPTION=DSC/K/A,TARGET=TRG/K,QUIET=Q/S

        You then have to enter an argument list according to this template
        or you can enter "?" to get the brief description as shown above.

        Description of the parameters:

        The parameter represented by the keyword FILES consists of a list
        of names. A name can be any valid AmigaDOS file name or a pattern
        containing AmigaDOS wildcards. All files in this list will
        be converted by "Cvt". The keyword may be omitted.

        The parameter with the keyword DESCRIPTION (abbreviated as DSC)
        may not be omitted. It specifies the file name of the conversion
        description (full path name). Note that also the keyword may not
        be omitted.

        The parameter TARGET (abbreviated as TRG) is optional. If you
        specify it, "Cvt" will write the converted files to the given
        directory (see "duplication mode", chapter 2). Note that also
        the keyword may not be omitted.

        If you wish "Cvt" to produce no output you must specify the
        switch QUIET. It may be abbreviated as "Q".


        ***************************************************************


        If you find any bugs or you have any ideas how to improve this
        this product, then contact me:

              ///   Rainer Koppler
             ///    Stelzhamerstrae 9
        \\\ ///     A-4623 Gunskirchen
         \\X//      Austria/Europe

        internet: rainer@soft.uni-linz.ac.at
